home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / reviews / fgrep.doc < prev    next >
Text File  |  1989-09-20  |  26KB  |  646 lines
  1.                                   FGREP 1.71
  2.                                   ----------
  3.  
  4.         "|" denotes changes in the recent versions.
  5.  
  6.  
  7.         Purpose
  8.         -------
  9.         FGREP (Fast GREP) is a small utility that can be used to find
  10.         strings of characters in ASCII text files, and arbitrary
  11.         sequences of bytes in other files.  String search capabilities
  12.         are not extensive (no regular expressions), but FGREP is small
  13.         and very, very fast.  FGREP is intended to replace DOS's FIND
  14.         filter with something faster and more flexible.
  15.  
  16.         UNIX people: we fully realize that this isn't the grep or fgrep
  17.         with which you are familiar.  We know that the RE in GREP means
  18.         "regular expressions" and we know that we don't support regular
  19.         expressions.  However, the name serves to point people in the
  20.         right direction.  Please don't write to tell us that this "isn't
  21.         really grep".
  22.  
  23.  
  24.         Syntax
  25.         ------
  26.         FGREP's syntax is
  27.  
  28.       |         FGREP [-abBceflmMopsvwx01] target {@file}
  29.  
  30.         Looks complicated, lots of switches, but the most common use is
  31.         very simple:
  32.  
  33.                 FGREP hello myfile.txt
  34.  
  35.         This command would display all lines of MYFILE.TXT that contain
  36.         the string "hello".
  37.  
  38.  
  39.         Targets
  40.         -------
  41.         The target is what you're looking for in the file.  There are
  42.         two ways to specify targets: as strings and as series of
  43.         hexadecimal bytes.  The two can be combined in a single target
  44.         specification.
  45.  
  46.         Strings are sequences of ASCII characters, like "hello".
  47.         Normally, you can just type in the string and forget it, but you
  48.         may have to "delimit" the string, i.e., bracket it by a pair of
  49.         matching non-alphanumeric characters (anything except - and $):
  50.  
  51.             'string'
  52.             /string/
  53.             .string.
  54.  
  55.         Choose a delimiter that does not appear in the string.  This is
  56.         no good:
  57.  
  58.             'you've made a mistake'
  59.  
  60.         Delimiters are required for a string target if any of these four
  61.         conditions are met:
  62.  
  63.             -- it is combined with hex byte sequences (more below)
  64.             -- it contains spaces or tabs
  65.             -- it begins with a non-alphanumeric character
  66.             -- it contains the DOS redirection characters < > |.
  67.  
  68.         In the last case, the string MUST be delimited by double quotes
  69.         ("), otherwise DOS will interpret it as redirection.
  70.  
  71.         Examples of valid string targets:
  72.  
  73.                 mov
  74.                 ax
  75.                 "two words"     (requires delimiter: contains a space)
  76.                 '/7'            (begins with non-alphanumeric)
  77.                 "f->x"          (contains ">", must use double quotes)
  78.  
  79.         It is always OK to delimit a string, even if delimiters are
  80.         unnecessary.
  81.  
  82.         REMEMBER that if the target contains DOS redirection characters
  83.         (<, >, or |), it MUST be delimited with double quotes ("") or
  84.         DOS will try to perform unwanted redirection.  For example:
  85.  
  86.             FGREP "a <= b" myfile.pas
  87.  
  88.         Hex byte sequences are used for binary file searching when the
  89.         bytes to be searched for are non-displayable characters or make
  90.         no sense as strings (e.g., program code).  They are specified as
  91.         pairs of hexadecimal bytes introduced by a leading '$':
  92.  
  93.             $EF
  94.             $CD21           (CDh, 21h)
  95.             $CD$21          (identical; either format is OK)
  96.             $00FFFE00       (00h, FFh, FEh, 00h)
  97.             $CD 21          (ILLEGAL: no spaces permitted)
  98.  
  99.         You can combine strings and hex sequences by using a '+':
  100.  
  101.             "abc"+$E74A+"def"
  102.  
  103.  
  104.         Target wildcards
  105.         ----------------
  106.         String targets (not hex targets) may contain one or mmore "?"
  107.         wildcards.  The ? will match any single non-null character in
  108.         the file.  E.g., "[?i]" will match "[si]", "[di]", etc., but not
  109.         "[i]".  Wildcards are not permitted when hex byte sequences are
  110.         used.
  111.  
  112.         If you want to search for the '?' character literally, use
  113.         '\?'.  For example, the target
  114.  
  115.                 what\?
  116.  
  117.         will search for the literal string "what?".
  118.  
  119.  
  120.         Specifying target files
  121.         -----------------------
  122.         You can list zero (see "Redirection"), one, or multiple files to
  123.         be searched.  Files listed may include DOS's * and ? wildcards.
  124.         Paths may be specified.  Examples:
  125.  
  126.             myfile.txt
  127.             *.txt
  128.             *.*
  129.             this.c that.c other.c
  130.             *.c *.pas
  131.             C:\UTIL\*.* D:\SYS\*.*
  132.             E:\LIBRARY\*.D?C
  133.  
  134.  
  135.       | File lists
  136.       | ----------
  137.       | If the name of a file on the command line is prefixed with an
  138.       | '@' character (e.g., '@list.txt'), the file is assumed to be a
  139.       | text file containing the names of files to be searched.  For
  140.       | example:
  141.       |
  142.       |     fgrep hello @files.lst
  143.       |
  144.       | FGREP will assume that the file FILES.LST is a text file that
  145.       | contains the names of files to be searched.  Each line of such a
  146.       | file should contain the name(s) of one or more files to be
  147.       | searched.  Files in file lists are specified exactly as are
  148.       | files named on the command line, except that you can't use
  149.       | another '@' file list; that is, file lists can't be nested.
  150.       |
  151.       | Here is an example of a valid list file:
  152.       |
  153.       |     this.c
  154.       |     c:\c\*.c d:\c\*.c
  155.       |     d:\misc\*.txt
  156.       |
  157.       | The name specified for the list file cannot contain wildcards;
  158.       | that is, this is illegal:
  159.       |
  160.       |     fgrep hello @lists.*        (WRONG)
  161.       |
  162.       | If you want to search for text in a file whose name begins with
  163.       | an '@', use a double '@'.  For example,
  164.       |
  165.       |     fgrep hello @@foo.txt
  166.       |
  167.       | will search for 'hello' in the file @FOO.TXT.
  168.  
  169.  
  170.         Redirection
  171.         -----------
  172.         If no file is listed, FGREP will take its input from the
  173.         standard input device, permitting redirection.  For example:
  174.  
  175.             DIR | fgrep pas
  176.  
  177.         would display any lines from a directory listing that contain
  178.         the string "pas".  Or,
  179.  
  180.             DIR | fgrep "<dir>"
  181.  
  182.         would list all subdirectories of the current directory.
  183.  
  184.         This command:
  185.  
  186.             arc p somefile foo.txt | FGREP somestring
  187.  
  188.         would display all lines from the file FOO.TXT in the archive
  189.         file SOMEFILE that contain "somestring".
  190.  
  191.         FGREP will terminate with an error if no file is listed and
  192.         standard input is not redirected.  Otherwise, it would be
  193.         waiting for keyboard input to scan, possibly leading you to
  194.         believe that it had hung up.
  195.  
  196.  
  197.         Examples of use
  198.         ---------------
  199.         Here are some examples of FGREP use:
  200.  
  201.         1. List all lines of MYFILE.TXT containing "hello"
  202.  
  203.             FGREP hello myfile.txt
  204.  
  205.         2. List all lines of all *.C files in the current directory that
  206.         contain "include foo.c":
  207.  
  208.             FGREP "include foo.c"  *.c
  209.  
  210.         3. List all lines from FILEA.EXT, FILEB.EXT, and FILEC.EXT that
  211.         contain the string "abcd" followed by any character:
  212.  
  213.             FGREP abcd? filea.ext fileb.ext filec.ext
  214.  
  215.         4. Display occurrences of the byte CDh followed by 21h (a DOS
  216.         call) in the program MYPROG.EXE:
  217.  
  218.             FGREP $CD21 myprog.exe
  219.  
  220.         5. Display occurrences of the string "abc" followed by a byte of
  221.         zeroes in all files in the C:\UTIL and D:\SYS:
  222.  
  223.             FGREP 'abc' + $00 c:\util\*.* d:\sys\*.*
  224.  
  225.  
  226.         Output
  227.         ------
  228.         FGREP's default screen output looks like this:
  229.  
  230.                 **File <filename>
  231.                 [text of lines containing string]
  232.                 **File <filename>
  233.                 [text of lines containing string]
  234.  
  235.         I